EMu server configuration

This section outlines the EMu server configuration required to use OpenID Connect.

User Accounts

As user account details are administered via the identity provider, no server-side Unix user accounts are required to use OIDC. The emu user account is, however, still required for server-side administration.

If the traditional Unix passwd or shadow files are used for server-side authentication of the emu user, it should not be necessary to install the Pluggable Authentication Module (PAM) libraries required to support other authentication methods such as Lightweight Directory Access Protocol (LDAP) or Active Directory (AD).

Identity Provider Configuration

An entry for each identity provider must be added to the Texpress configuration file $TEXHOME/etc/openid/providers. The providers file must be formatted as a JavaScript Object Notation (JSON) array. Each element of the array is an object that represents a single identity provider. The following object elements should be specified for each provider:

Element	Requirement	Details
`name`	Optional	Specifies the title used to identify the entry. Can be any value but should identify the provider. For example: Azure Identity Provider for EMu
`discovery`	Optional	Specifies the `OpenID Connect metadata document` value obtained from the Identity Provider Application Registration. For example: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0/.well-known/openid-configuration If this value is not supplied, you must provide a `jwks_uri` element.
`client_id`	Mandatory	Specifies the `Application (client) ID` value obtained from the Identity Provider Application Registration. For example: 11111111-1111-1111-1111-111111111111
`issuer`	Mandatory	Confirm the issuer (i.e. the identify provider) of ID tokens passed to the server. For example: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0 This value can be extracted from the `OpenID Connect metadata document`. For example, to download the metadata document and extract the `issuer` value: $ curl --silent 'https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0/.well-known/openid-configuration'\| jq '.issuer'"https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0" Note: The `jq` utility is a command line processor for JSON documents. If it is not available, you can just extract the `issuer` value manually.
`redirect_port`	Optional	Some OIDC providers require the redirect URL to use a specific port. The `redirect_port` element allows for the specification of a specific port to use for the response redirect URL.
`jwksfile`	Mandatory	Specify the file name used by the server for caching downloaded discovery data. This can be any value but should be different to other provider `jwksfile` values. For example: azure.jwks
`jwks_uri`	Optional	Used for token verification when a `discovery` value is not supplied.
`redirect_port`	Optional	Assigns a random port number in the range of `49152` to `65535` for the successful login redirect URL. Setting `redirect_port` forces the redirect URL to use the specified port.

Note: Further details can be found in the $TEXHOME/etc/openid/README file.

Example

The following is a full example of a providers file for both the Microsoft Azure AD and Google Cloud Platform identity providers:

[
  {
    "name": "Azure Identity Provider for EMu",
    "discovery": "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0/.well-known/openid-configuration",
    "client_id": "11111111-1111-1111-1111-111111111111",
    "issuer": "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0",
    "redirect_port": "54321",
    "jwksfile": "azure.jwks"
  },
  {
    "name": "Google Identity Provider for EMu",
    "discovery": "https://accounts.google.com/.well-known/openid-configuration",
    "client_id": "111111111111-11111111111111111111111111111111.apps.googleusercontent.com",
    "issuer": "https://accounts.google.com",
    "jwksfile": "google.jwks"
  }
]

Username Configuration

The username supplied by the identity provider via OIDC is likely to be the user's email address and must match the server-side username specified in the EMu Registry.

This is not an issue for new users or installations but may be problematic for existing users as the username already specified in the EMu Registry may not match the username supplied by the identity provider.

This can be resolved using the Texpress Username Map facility, which can be used to map an OpenID username to another username.

This feature allows you to change the username obtained from the identity provider to another username after successful authorisation via OpenID Connect. This is useful primarily to map an OpenID username to the username of an already existing user.

Attention

It should not be necessary to use the Username Map feature for new users or new EMu installations.

The benefits of this approach are:

The user's existing Registry entries do not need to be updated.
Because the non-OpenID username of existing users will be extant in the system (e.g. in Record Level Security column values, possibly in Inserted/Modified By column values and the Audit module User column value), we do not end up with two different usernames in the system that refer to the same user.

The Username Map is specified in the file $TEXHOME/etc/openid/usermap. Each mapping is specified on a single line and must be formatted as:

For example, the following line is used to map the OpenID username Charlie.Brown@peanuts.com to the existing username charlieb:

Charlie.Brown@peanuts.com charlieb

Note

The existing username (e.g. charlieb above) does not have to be a valid Unix username, i.e. there does not have to be an Unix account specified for that user on the EMu server.

Further details can be found in the $TEXHOME/etc/openid/usermap file.